Azure Maps Route Service (preview:2024-07-01)

2024/12/19 • 1 updated methods

Route_PostRouteDirectionsBatch (updated)
Description :  The `Route Directions Batch` API is an HTTP `POST` request that sends batches of up to **100** queries in a single call to the [Route Directions](/rest/api/maps/route/post-route-directions?view=rest-maps-2024-07-01-preview) API. >[!Important] >By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional details. ### Submit Synchronous Batch Request The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API. ``` POST https://atlas.microsoft.com/route/directions:batch?api-version=2024-07-01-preview ``` ### POST Body for Batch Request To send the _directions_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _directions_ queries: ``` { "batchItems": [ { "optionalId": "bbc9c0f6-ab52-49d8-a788-a658fa654c94", "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "coordinates": [ -122.3368, 47.614988 ], "type": "Point" }, "properties": { "pointIndex": 0, "pointType": "waypoint" } }, { "type": "Feature", "geometry": { "coordinates": [ -122.316067, 47.606356 ], "type": "Point" }, "properties": { "pointIndex": 1, "pointType": "waypoint" } } ], "optimizeRoute": "fastestWithoutTraffic", "routeOutputOptions": [ "routeSummary" ], "maxRouteCount": 3, "travelMode": "driving" }, { "optionalId": "a191de3c-1268-4986-98f0-03f0a5d9302a", "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "coordinates": [ -122.3368, 47.614988 ], "type": "Point" }, "properties": { "pointIndex": 0, "pointType": "waypoint" } }, { "type": "Feature", "geometry": { "coordinates": [ -122.316067, 47.606356 ], "type": "Point" }, "properties": { "pointIndex": 1, "pointType": "waypoint" } } ], "optimizeRoute": "shortest", "routeOutputOptions": [ "routeSummary" ], "maxRouteCount": 2, "travelMode": "driving" } ] } ``` A _directions_ batchItem object can accept any of the supported _directions_ [Request body](/rest/api/maps/route/post-route-directions?view=rest-maps-2024-07-01-preview#request-body) The batch should contain at least **1** query. ### Batch Response Model The batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types: - [`DirectionsResponse`](/rest/api/maps/route/post-directions#response) - If the query completed successfully. - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.
Reference :  Link ¶

⚶ Changes

{
  "#id": "Route_PostRouteDirectionsBatch",
  "Description": {
    "new": "\n\n\nThe `Route Directions Batch` API is an HTTP `POST` request that sends batches of up to **100** queries in a single call to the [Route Directions](/rest/api/maps/route/post-route-directions?view=rest-maps-2024-07-01-preview) API.\n>[!Important]\n>By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional details.\n\n### Submit Synchronous Batch Request\nThe Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API.\n```\nPOST https://atlas.microsoft.com/route/directions:batch?api-version=2024-07-01-preview\n```\n### POST Body for Batch Request\nTo send the _directions_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _directions_ queries:\n\n\n```\n{\n  \"batchItems\": [\n    {\n      \"optionalId\": \"bbc9c0f6-ab52-49d8-a788-a658fa654c94\",\n      \"type\": \"FeatureCollection\",\n      \"features\": [\n        {\n          \"type\": \"Feature\",\n          \"geometry\": {\n            \"coordinates\": [\n              -122.3368,\n              47.614988\n            ],\n            \"type\": \"Point\"\n          },\n          \"properties\": {\n            \"pointIndex\": 0,\n            \"pointType\": \"waypoint\"\n          }\n        },\n        {\n          \"type\": \"Feature\",\n          \"geometry\": {\n            \"coordinates\": [\n              -122.316067,\n              47.606356\n            ],\n            \"type\": \"Point\"\n          },\n          \"properties\": {\n            \"pointIndex\": 1,\n            \"pointType\": \"waypoint\"\n          }\n        }\n      ],\n      \"optimizeRoute\": \"fastestWithoutTraffic\",\n      \"routeOutputOptions\": [\n        \"routeSummary\"\n      ],\n      \"maxRouteCount\": 3,\n      \"travelMode\": \"driving\"\n    },\n    {\n      \"optionalId\": \"a191de3c-1268-4986-98f0-03f0a5d9302a\",\n      \"type\": \"FeatureCollection\",\n      \"features\": [\n        {\n          \"type\": \"Feature\",\n          \"geometry\": {\n            \"coordinates\": [\n              -122.3368,\n              47.614988\n            ],\n            \"type\": \"Point\"\n          },\n          \"properties\": {\n            \"pointIndex\": 0,\n            \"pointType\": \"waypoint\"\n          }\n        },\n        {\n          \"type\": \"Feature\",\n          \"geometry\": {\n            \"coordinates\": [\n              -122.316067,\n              47.606356\n            ],\n            \"type\": \"Point\"\n          },\n          \"properties\": {\n            \"pointIndex\": 1,\n            \"pointType\": \"waypoint\"\n          }\n        }\n      ],\n      \"optimizeRoute\": \"shortest\",\n      \"routeOutputOptions\": [\n        \"routeSummary\"\n      ],\n      \"maxRouteCount\": 2,\n      \"travelMode\": \"driving\"\n    }\n  ]\n}\n ```\n\nA _directions_ batchItem object can accept any of the supported _directions_ [Request body](/rest/api/maps/route/post-route-directions?view=rest-maps-2024-07-01-preview#request-body) \n\n\nThe batch should contain at least **1** query.\n\n\n### Batch Response Model\nThe batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types:\n\n  - [`DirectionsResponse`](/rest/api/maps/route/post-directions#response) - If the query completed successfully.\n\n  - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.\n\n\n",
    "old": "\n\n\nThe `Route Directions Batch` API is an HTTP `POST` request that sends batches of up to **100** queries in a single call to the [Route Directions](/rest/api/maps/route/post-directions?view=rest-maps-2023-10-01-preview) API.\n>[!Important]\n>By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional details.\n\n### Submit Synchronous Batch Request\nThe Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API.\n```\nPOST https://atlas.microsoft.com/route/directions:batch?api-version=2023-10-01-preview\n```\n### POST Body for Batch Request\nTo send the _directions_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _directions_ queries:\n\n\n```\n{\n  \"batchItems\": [\n    {\n      \"optionalId\": \"bbc9c0f6-ab52-49d8-a788-a658fa654c94\",\n      \"type\": \"FeatureCollection\",\n      \"features\": [\n        {\n          \"type\": \"Feature\",\n          \"geometry\": {\n            \"coordinates\": [\n              -122.3368,\n              47.614988\n            ],\n            \"type\": \"Point\"\n          },\n          \"properties\": {\n            \"pointIndex\": 0,\n            \"pointType\": \"waypoint\"\n          }\n        },\n        {\n          \"type\": \"Feature\",\n          \"geometry\": {\n            \"coordinates\": [\n              -122.316067,\n              47.606356\n            ],\n            \"type\": \"Point\"\n          },\n          \"properties\": {\n            \"pointIndex\": 1,\n            \"pointType\": \"waypoint\"\n          }\n        }\n      ],\n      \"optimizeRoute\": \"fastestWithoutTraffic\",\n      \"routeOutputOptions\": [\n        \"routeSummary\"\n      ],\n      \"maxRouteCount\": 3,\n      \"travelMode\": \"driving\"\n    },\n    {\n      \"optionalId\": \"a191de3c-1268-4986-98f0-03f0a5d9302a\",\n      \"type\": \"FeatureCollection\",\n      \"features\": [\n        {\n          \"type\": \"Feature\",\n          \"geometry\": {\n            \"coordinates\": [\n              -122.3368,\n              47.614988\n            ],\n            \"type\": \"Point\"\n          },\n          \"properties\": {\n            \"pointIndex\": 0,\n            \"pointType\": \"waypoint\"\n          }\n        },\n        {\n          \"type\": \"Feature\",\n          \"geometry\": {\n            \"coordinates\": [\n              -122.316067,\n              47.606356\n            ],\n            \"type\": \"Point\"\n          },\n          \"properties\": {\n            \"pointIndex\": 1,\n            \"pointType\": \"waypoint\"\n          }\n        }\n      ],\n      \"optimizeRoute\": \"shortest\",\n      \"routeOutputOptions\": [\n        \"routeSummary\"\n      ],\n      \"maxRouteCount\": 2,\n      \"travelMode\": \"driving\"\n    }\n  ]\n}\n ```\n\nA _directions_ batchItem object can accept any of the supported _directions_ [Request body](/rest/api/maps/route/post-directions?view=rest-maps-2023-10-01-preview#request-body) \n\n\nThe batch should contain at least **1** query.\n\n\n### Batch Response Model\nThe batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types:\n\n  - [`DirectionsResponse`](/rest/api/maps/route/post-directions#response) - If the query completed successfully.\n\n  - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.\n\n\n"
  },
  "Summary": {
    "new": "Use to send a batch of queries to the [Route Directions](/rest/api/maps/route/post-route-directions?view=rest-maps-2024-07-01-preview) API in a single synchronous request.",
    "old": "Use to send a batch of queries to the [Route Directions](/rest/api/maps/route/post-directions?view=rest-maps-2023-10-01-preview) API in a single synchronous request."
  }
}

⚼ Request

POST:  /route/directions:batch
{
x-ms-client-id:
{
Description: Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Microsoft Entra ID security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance. ,
Required: False ,
}
string ,
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
Accept-Language:
{
Description: Language in which routing results should be returned. For more information, see [Localization support in Azure Maps](https://learn.microsoft.com/en-us/azure/azure-maps/supported-languages#routing-v2-services-preview-supported-languages). ,
Required: False ,
}
string ,
routeDirectionsBatchRequest:
{
Description: The list of route directions queries/requests to process. The list can contain a max of 100 queries for sync version and must contain at least 1 query. ,
Required: True ,
}
{
batchItems:
{
Description: The list of queries to process. ,
Required: False ,
}
[
object ,
]
,
}
,
}

⚐ Response (200)

{
summary:
{
Description: Summary for the batch request ,
Required: False ,
}
{
successfulRequests:
{
Description: Number of successful requests in the batch ,
Format: int32 ,
Required: False ,
}
integer ,
totalRequests:
{
Description: Total number of requests in the batch ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
batchItems:
{
Description: Array containing the batch results. ,
Required: False ,
}
[
object ,
]
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}